																																			  	G-Force 
															   Extras


       Currently, G-Force is in need of better documentation.  Please realize that it takes a great deal of time and effort to make useful and effective documentation, so I'd love for you to take some initiative by documenting your own (or already included) configs!  


G-Force As A Standalone Application

     The G-Force application in the Extras folder uses your sound-in port as input.  It's useful if you want to visualize sound that's not in an mp3 format, such as an audio CD, line input from an A/V source, or a microphone.

1)  Open your "Monitors & Sound" control panel and click on the sound settings button.
2)  Change the "Sound Monitoring Source" popup menu to whatever sound source you want to monitor (Built-in Mic, Sound In, and CD are the most commonly used).
3)  Make sure the G-Force application is in a folder that also has the 4 support folders. 


G-Force Screenshots

    The folder "Screenshots" contains images users have sent in that make great desktop backgrounds and are generally fun to look at.  Try to keep an eye out for config combos that makes for great G-Force output and save a snapshot of it.  When you get enough good images together, just email them to me, and they'll be in the next release of G-Force.


More G-Force Configs

    The folder "More G-Force Configs" inside the Extras folder contains even more configs users have sent in.  Now that there's so many configs, only the sharpest and most original configs make it to the installed configs folder, but the ones in "More G-Force Configs" still definitely stand out.  Of course, you can always add and remove particular configs to and from the "G-Force Configs" folder.


Capturing Video Output

     You can get WhiteCap and G-Force to save what you see in the their window in the form of a QuickTime movie.  <Insert more docs!!>.  Here's the basic steps:
1)  Run WhiteCap/G-Force (as a plugin or the standalone application)
2)  Type the key that starts a sound capture to disk ('\' is the default key) to tell WhiteCap/G-Force where to dump the sound data.  Once you do this, you're in capture mode and things will appear  frozen but WhiteCap/G-Force is busy writing to disk.  
4)  To end the capture, type the same key you typed to start the capture.
5)  Make sure the standalone applcation is located in the same folder as the "G-Force Configs" folder.
6)  In the standalone application and select "Convert To QuickTime" from the File menu.  It will prompt you select a capture file, so select the capture file you want converted to QuickTime. 
7)  After you change any settings and choose a destination quicktime file name, you'll see G-Force begin to internally playback the audio data you captured.  You won't hear anything because the captured data is in a format only G-Force understands, but you're free to run scripts and use key commands in G-Force.
*** Docs missing because capture isn't fully complete yet


Background

     Theres 4 main elements that affect what you see in the G-Force window, and they correspond to each of the configs folders:  Waveshapes, DeltaFields, ColorMaps, Particles, and Scripts
 A waveshape is something that turns a short sound clip into lines and dots to be drawn (ie, something graphical).  
  Next, imagine a chalk drawing on a chalkboard.  Someone hands you a big list, and its a list of commands that all resemble, "find the point (a, b) on the chalkboard, erase what's there, and in its place draw what you have drawn at point (c, d)."  If you follow every command on the list in order, you're left with a different picture on your chalkboard than when you started.  In effect, youve transformed  your initial image into a new one.  In G-Force, something I call a DeltaField acts like this list of commands, except that instead of chalkboards, it's meant for the G-Force window.  A DeltaField is a recipe that makes a new image or "frame" from an existing one.  Like a recipe, it's meant to be used over and over.  If you open one up, youll just see it contains two equations that express a source coordinate as that depends on a destination (within the next frame)
  Whenever G-Force is running, it has one waveshape loaded and one deltafield loaded at any given time.  It's constantly repeats 4 steps: 
1)  Use the current deltafield on the current frame to get a new image/frame
2)  Sample some sound and give it to the current waveshape
3)  Draw the output from that waveshape on top of the new frame supplied from step 1
4)  Show the frame on the screen
  G-Force will randomly shuffles though waveshapes, deltafields, and colormaps (see the WInt, DInt, and CInt prefs)
  A ColorMap a list of 256 RGB colors.  G-Force does it's work on an "8-bit" image offscreen that you never see, meaning that each pixel within G-Force has has a value from 0 to 255.  When G-Force needs to draw a pixel, it uses the current ColorMap to lookup the RGB color for each pixel value.  In other words, a ColorMap is a one-way translator that turns pixel index values into RGB colors able to be drawn.  
  Particles are the things that randomly appear and disappear every few seconds in G-Force.  They're the extra things you see flying around in the G-Force window now and then.  They're the same thing as waveshapes except that G-Force treats particles a little differently:  Only one waveshape (or a morph of two) is ever being drawn at a time, while there can be one or more particles flying around at any given time in addition  to the current waveshape.  Particles are just waveshapes that appear when G-Force rolls some dice and the dice happen to come up a certain way (see the PPrb pref below).  You'll notice that there's two Particle folders, "Particles" and "Particles (Non-Auto)".  Particles in the "non-auto" folder will never be selected to be automatically run and can only be run by a script calling them directly.  For example, if you made a particle that displayed the text, "Blue Light Special", you wouldn't want it run just randomly--you'd instead only run it at certain times by storing it in the non-auto folder and running it from a script file or from a key-script (see the section on scripting).
  The text files in the "Scripts" folder are in a special format that contain G-Force commands and time indexes when they are to be executed.  With some time and practice, you could make a script to your favorite song that does all kinds of things as certain beats and rhythms unfold.


Customizing G-Force

     You can customize G-Force in many ways by editing the settings and flags stored its preferences file.  Note that each version of G-Force writes its own seperate set of preferences (ex, the SoundJam version writes "G-Force Prefs (SoundJam)" while the standalone verion writes "G-Force Prefs (Standalone)").  Since G-Force writes/updates its preferences file only when it exits, you'll have to run and exit G-Force at least once before you'll find a G-Force prefs file to edit.  Do a search for "G-Force Prefs" on your system to see where G-Force has written its prefs file.  The following list describes each parameter in the prefs file, and you should become comfortable with how G-Force runs before making any changes.  Finally, if you find G-Force acting strangely after you edit its prefs file, just delete the prefs file and G-Force will make a new "factory" set of prefs.

SSvr - (Screen Saver)  This parameter is used to make GF a screen saver, and tells GF the number of minutes to wait before switching to full screen once your computer has been left idle.  You can disable this action by setting it to 0 or -1 (it's disabled by default). 

MaxX, MaxY - (Max Dimensions/Letterbox Size) These set a limit on the pixel dimentions of GF.  For example, 640x480 may be too slow for your computer, but setting MaxY to 300 will increase framerate and you'll still have most of your screen filled up.

FWin - (Floating Window) If this is 1, GF will try to "float" the G-Force window above other windows.  This may not apply or be possible depending on your audio player and/or OS.  Turn of floating window by setting it to 0.

FS_X, FS_Y - (Fullscreen Dimensions) This tells GF what fullscreen resolution you prefer.  When you tell GF to go fullscreen, it will use the dimentions specified here.  Be sure you only put sizes you know your screen can support, and if bad things start to happen, just stick with 640x480.  Remember, these dimensions specifcy a device resolution, so you can't just put any values you like here (use MaxX and MaxY to tell GF to live in a smaller rect).

FS_D - (Fullscreen Depth) This is the depth GF will choose when it goes fullscreen (choose only 8, 16, or 32).  8 and 32 bit will produce the same color-quality frames, but 32 will be slower because more data is moving around.  16 will be slightly faster than 32 but may show small decreases in color quality.  The only time you don't want to use 8 for FS_D is if your system is having problems using 8.  The 'F' key shows you the current frame rate and can help you discover which depth is fastest for your system.

FS_# - (Fullscreen Device Num) This tells GF what display device you'd like it to be fullscreen on.  0 is your main screen, 1 is the next, 2 is the next, and so on.  If you have mulitple display devices, you'll have to start from 0 and figure out what number corresponds to your display device.

FS_F - (Fullscreen Refresh Frequency), (For Macs only) - When this is 0, the system default refresh rate is used for whatever resolution is specified by FS_X, FS_Y, FS_D, and FS_#.  Most of the time, this is fine since the system will choose the highes refresh frequency possible, but some systems have A/V output that needs to be a specific frequency (ex, set FS_F="60").

ShwT - (Show Config Titles)  If this is 1, GF will say when its bringing on a different ColorMap, WaveShape, DeltaField, or Particle.  If it's 0, GF won't print anything when a different config starts (ex, "Loaded ColorMap: Teal").  It's useful to have on when you want get familiar each config (and what its name is).

CDur - (Console Duration) This is how many seconds GF's text console is displayed when GF outputs something to the console.  Remember that your frame rate will decrease whenever the console is visible, so it may get annoying if you set CDur really high (and don't have a really fast CPU) because the console will take such a long time to go away.

CLin - (Console Line Duration) This is how many seconds a line will remain visible in GF's console until it's erased.  

TFnt - (Text Font) This is the text font GF will use when drawing track text.

TSze - (Text Size) This is the text size GF will use when drawing track text.

T? - Each frame, GF evaluates what you have expressed in T?:  If it's greater than 0 and wasn't greater than 0 the previous frame, GF will look for a config named "Track Info" and run it.  In other words, 'T?' acts as a trigger that makes GF run a specific config.  As a trigger, 'T?' must "reset" by getting less than or equal to 0 before "Track Info" will be launched again.  You could use 'T?' for anything, but it used by default to run a config that displays track info when a new track starts. 'T?' has access to 't' and 'LAST_SONG_START' (both in seconds).  Here's some examples:
"1 + LAST_SONG_START - t"  // "Track Info" is run whenever a new song starts
"-1"                       // "Track Info" is never launched
"1 - t % 200"              // Starts "Track Info" every 200 seconds
// Starts the text when a new song starts and/or starts it every 200 seconds
"pos( 1 + LAST_SONG_START - t ) + pos( 1 - t % 200 )"

WInt - (Waveshape Interval) Number of seconds GF uses a waveshape before switching to a new waveshape.  For example, if you want to see a new waveshape every 15 seconds, set this to 15.  In another example, you can force GF to always be morphing between waveshapes by setting this to 0.  (ex, "15", "10 + rnd( 10 )", "0")

CInt - (ColorMap Interval) Number of seconds GF uses a colormap before switching to a new colormap.  This pref is similar to WInt and DInt.

DInt - (DeltaField Interval) Number of seconds GF uses a deltafield before switching to a new deltafield.  It takes a significant amount of CPU power to ready a deltafield for use, and GF chips away at this task each frame  (this is why you get a spinning cursor when you resize GF's window).  If you set DInt too low, GF will be unable to switch deltafields every DInt number of seconds because you're not giving GF enough time.  If this happens, GF will simply run normally until it's finished readying in oncoming deltafield.

MDur - (Morph Duration) When GF switches waveshapes, it has to know how long to make the transition from one waveshape to the next waveshape.  It decides this length of time by evaluating 'MDur'.  For example, setting MDur to "5 + rnd( 6 )" means each transition will never be shorter than 5 seconds or longer than 11 seconds.

NoBo - (No Widow Border) If 1, GF will try to make its window borderless.  This depends on what audio player and/or OS G-Force is running on.

KMap - (Key Map) This is how G-Force knows what to do when you press a certain key.  If G-Force sees you press a key that's not in the following list, it will pass that keystroke to your audio player.  For example, suppose 'A' did something important in your audio player but was also used in G-Force by default.  You could assign what 'A' does in G-Force to a different key by replacing the 'A' in KMap with another character.  'KMap' is just a list of characters, and the following is a list of what character number does what (ex, 'Y' is the 4th character in "TLRY`OKGFASDQWE,.M[]{}P\\U~~~~~0123456789)!@#$%^&*(" so pressing 'Y' will trigger the 4th command.
01    Display Track Title
02    List the names of the currently loaded config
03    Calc the frame rate
04    Spawn New Particle
05    Toggle fullscreen
06    Toggle showing config name when loaded
07    Toggle DeltaField transitions
08    Start slideshow (all)
09    Stop/Freeze slideshow (all)
10-12 Prev/Next/StartShow DeltaField
13-15 Prev/Next/StartShow ColorMap
16-18 Prev/Next/StartShow WaveShape
19-20 Dec/Inc mag() scale
21-22 Dec/Inc number of sub-samples per sample
23    Toggle Particles
24    Toggle Capture
25    Reload current DeltaField
26    (Reserved)
27    (Reserved)
28-29 (Unused)
30-49 Execute script S0 TO S19 (30 executes S0, 31 executes S1, etc...)

S0 through S19 - (Script Definitions)  When G-Force receives a keystroke that's mapped to a S-command (see above) that G-Force execute.  For example, pressing the 32nd key in the KMap parameter makes GF execute the text in paramter S2, and pressing the 41st key in the keymap executes the text in S11.  The "Scripting G-Force" section below describes how the text in one of these S-parameters is 'executed'.

PPrb - (Particle Probability) Once per second, GF picks a random number from 0 to 1 and evaluates the PPrb expression.  If the random number is less than PPrb, a new particle is spawned/started.  The variable NUM_PARTICLES is how many particles are currently running and is usually used in the 'PPrb' function.  The PPrb should somehow use NUM_PARTICLES to decrease in value or else GF will just keep spawning new particles indefinitely!  (Note how the default expression for PPrb has this property)

PDur - (Particle Duration) When GF spawns a new particle, it assigns it a lifetime/duration.  When that lifetime is up, the particle fades out.  GF uses PDur whenever a particle is spawned and uses the value returned as the lifetime (in seconds).   A particle is allowed to override PDur by defining its own PDur parameter (and G-Force uses that instead).  See "Spinners".

P_On - (Particles On)  If this is 0, GF will not automatically spawn any paticles on it's own (ie, this is a way to disable particles from automatically appearing if you don't want them to appear).  If this is 1, GF will use the PPrb pref to decide when to start a new particle (see above).  See the command list to see what command toggles 'P_On'.

FldT - (Field Transitions On)  If this is 1, GF will transition/morph between each DeltaField when GF is in DeltaField slideshow mode.  If it's 0, when GF is in DeltaField slideshow mode, GF will switch to the oncoming field in one frame.  Field transitions are a very cool effect, but it's recommended they're turned off your processor below 300-450MHz.  See the command list to see what command toggles 'FldT'.

SNum - (Sample Size) How many sub-samples are in each sample.  Terminology: a "sample" is a sequence of sub-samples (ie, integers) that form a short clip of audio.  So what is meant by "sample" really doesn't exist--it's just used to describe a sequence of integers that correspond to the current audio that G-Force is given for each frame.  So SNum is the resolution or size of each sample, and the number of values in mag(0..1) is SNum.  In a config, you can access 'SNum' by using NUM_SAMPLE_BINS.  Press the '?' key to see what keys will change SNum in real time (ie, commands 21 and 22).  

SScl - (Sample Scale) Scales the amplitude of the input (ie, every sub-sample is multiplied by this number).  If the music you play is soft, try increasing this to 1.5 or higher (1000 means 1.0 and 1500 means 1.5, etc).  Press the '?' key to see what keys will change SScl in real time (ie, commands 19 and 20).  

SSmo - (Sample Gauss Smooth Factor)  The higher number this is, the more the a sample will be smoothed out (ie, peaks and valleys will be less jagged).  To give you an idea, approximatly doubling/halving this number will double/half the amount of smoothing.  In other words, SSmo affects the amount of smoothing of mag(0..1).

FNum - (Frequency Sample Size) How many sub-samples are in each frequency sample and like SNum, FNum is a resolution: there are FNum number of values in fft(0..1).  The higher 'FNum' is, the more "bins" the frequency spectrum will be divided up into (note: "bin" is interchangable with "sub-sample from a frequency sample" and "freq sample" is interchangable with "freq spectrum").  See the background section for extra info.  In a config, you can access 'FNum' by using NUM_FFT_BINS.  If you're totally confused at this point, don't get upset--there's a lot to digest here--just see the documentation in the example configs, expecially the documentation of the Stps parameter in "Rotating Corridor".

FSmo - (Frequency Sample Smooth Factor) This is the same as 'SSmo' except that fft(0..1) is what's smoothed. 

FRge - (Frequency Range Per Bin) This is how "wide" of a frequency band a value from fft() is.  The larger FRge is, the wider frequncy band fft(0..1) will span. For example, if FRge is large then fft(0) may be the magnitude of the frequencies from 100 to 500 Hz, while if FRge is smaller then fft(0) may be the magnitude of the frequencies from 100 to 200 Hz.  You may want to read the background section for more information on frequency spectrums. 

FSrt - (Frequency Sample Start)  This controls or "anchors" what frequency fft(0) is.  'FSrt' controls the starting frequency of the freq spectrum and is independent of FRge and FNum.  The proportionality constant depends only on what build of WhiteCap or G-Force you're using (ex, Standalone, Winamp, SoundJam, etc).  In other words, the frequency bin returned by fft(x) is: const * ( FSrt + FRge * FNum * x ) Hz.

FFFT - (Frequency Sample Transform Fcn)  This parameter transforms input or "raw" freq values into the actual values accessed via fft().  For example, to increase the scale of fft(), just put a bigger scaling factor in front of the function (that's why there's no 'FScl' parameter).  Each build of WhiteCap/G-Force has a different default FFFT function because each audio player's fft data is massaged differently to make it look nice.  The variable W is the frequency, X is the raw fft value for that W, and the whole expression will be the new value of X.  As a whole, I've chosen functions that supress large fft values and amplify medium-level fft values. 

DMem - (DeltaField Cache Size)  This is the number of megabytes G-Force will use to keep precalculated DeltaFields around.  Unless you set this to the order of 50+ megs and maintain a modest window size, you won't see any benefit from caching DeltaFields.  This is because there's enough DeltaFields that until you can start holding at least half of them in memory, the chances G-Force will randomly select a field that's already in memory are small.  A field that's 640x480 is about 1.2 megs, and one half those dimentions is a quarter, 300k.  Setting 'DMem' is more useful when you're trying to produce a professional script--you'll need a few megs of cache so that your script can precompute fields that it will need at a certain time later.  If you didn't precompute the given field first, the user would see an ugly pause while GF computed the field on-demand.  Normally, GF computes the oncoming field by computing a small chunk of it each frame until it's done.  So if you have some sick system with a few hundred megs of RAM set DMem as big as you can--the framerate will eventually rise because GF won't need to compute fields twice.  Finally, when you change the dimensions of GF (ex, resize window or goto fullscreen), remember that GF cannot use fields computed for the old size and must recompute them.



Scripting G-Force

     G-Force has some basic scripting services if you want G-Force to display specific configs or actions upon a specific keystroke.  The folder "Scripts" contains text files that are a complete script for G-Force to follow.  The best way to learn how G-Force scripts work is by studying the "Example Script" in the Scripts folder.  
     The only way to launch a script or particle in the non-auto folder is use a key that's mapped to execute what's in the parameters S0 to S19.  "Key-script" text is located in your prefs text file and appear as text parameters named S0 through S19 (allowing you a maximum of 20 command lines).  To tell G-Force to execute a specific key-script, you must press the key that corresponds to that script ID.  For example, to execute S2, you'd have to press the key that G-Force has mapped to execute S2.  By factory default, pressing '0' executes S0, '1' executes S1, '2' executes S2, and so on (see the KMap pref).
     The format of a command line is a sequence of keystrokes and/or config names separated by semicolons.  In other words, whatever is between semicolons is one of two things: a letter that corresponds to a key command (as if you typed it in from the keyboard) or the filename of config to switch to.  When G-Force sees that its a config name, it will search all it's config folders for a matching name, allowing you to execute a config that's a waveshape, colormap, deltafield, particle, or script.  If it's a config name and the config happens to be a WaveShape or ColorMap, putting an asterisk after the title will cause G-Force to transition/morph from the present waveshape/colormap to what's been given (versus instantly switching to what's been given).  As examples for you, G-Force sets 4 sample scripts to S0, S1, and S2 whenever it makes a new pref file.  Inspect them below and note how G-Force executes each:

// Pressing '1'switches to the given deltafield, colormap, and waveshape
S1="Noise;Rotating Arcs;Aqua",

// Pressing '2' transitions/morphs to the given waveshape and a random colormap
S2="E;rotating arcs*",

// Pressing '3' displays the track text, transitions/morphs to a random waveshape and colormap, and starts 2 new particles
S3="T;E;M;Y;Y",

// Pressing '4' looks for the given configs to run
S4="My Cool Particle;Example Script",

Once you are comfortable with how key-scripts work in G-Force, you make your own by simply editing/adding S-parameters in your G-Force preferences file.  By factory default, since there's only 10 number keys, S10 through S19 are mapped to the characters you get when you press SHIFT and a numeral (see the default KMap string).  When you get confortable with how "Example Script" works, learn to make your own by adding to it.